SpringBoot 完整学习笔记

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * SpringBoot 启动类
 * @SpringBootApplication 组合注解,包含:
 * - @SpringBootConfiguration: 标记为配置类(等同于@Configuration)
 * - @EnableAutoConfiguration: 启用自动配置(根据classpath自动配置Bean)
 * - @ComponentScan: 扫描组件(扫描当前包及子包下的@Component、@Service、@Controller等)
 */
@SpringBootApplication  // 标记为SpringBoot应用的主配置类
public class DemoApplication {

    public static void main(String[] args) {
        // 启动 SpringBoot 应用
        // SpringApplication.run()会创建ApplicationContext、扫描Bean、启动内嵌Web服务器
        SpringApplication.run(DemoApplication.class, args);
        // 输出: Started DemoApplication in 2.5 seconds (JVM running for 3.0)
    }
}

package com.example.demo.controller;

import org.springframework.web.bind.annotation.*;

/**
 * HelloController
 * @RestController = @Controller + @ResponseBody
 * 返回 JSON 数据,而不是视图
 */
@RestController
@RequestMapping("/api")
public class HelloController {

    /**
     * GET 请求示例
     * 访问: http://localhost:8080/api/hello
     */
    @GetMapping("/hello")
    public String hello() {
        return "Hello, SpringBoot!";
    }

    /**
     * 带路径参数
     * 访问: http://localhost:8080/api/hello/张三
     */
    @GetMapping("/hello/{name}")
    public String helloName(@PathVariable String name) {
        return "Hello, " + name + "!";
    }

    /**
     * 带查询参数
     * 访问: http://localhost:8080/api/greet?name=张三&age=18
     */
    @GetMapping("/greet")
    public String greet(
        @RequestParam(defaultValue = "Guest") String name,
        @RequestParam(required = false) Integer age
    ) {
        return "Hello, " + name + "! Age: " + (age != null ? age : "未知");
    }

    /**
     * POST 请求示例
     * 接收 JSON 数据
     */
    @PostMapping("/user")
    public String createUser(@RequestBody User user) {
        return "Created user: " + user.getName();
    }
}

// User 类
class User {
    private String name;
    private Integer age;

    // Getters and Setters
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
}

@RestController
public class ConfigController {

    @Value("${server.port}")
    private int port;

    @Value("${spring.application.name}")
    private String appName;

    @Value("${my.config.version:1.0}")  // 默认值
    private String version;

    @GetMapping("/config")
    public String getConfig() {
        return "Port: " + port + ", App: " + appName + ", Version: " + version;
    }
}

// 配置类
@Component
@ConfigurationProperties(prefix = "my.config")
@Data  // Lombok 注解,自动生成 getter/setter
public class MyConfig {
    private String name;
    private String version;
    private String author;
}

// 使用配置
@RestController
public class ConfigController {

    @Autowired
    private MyConfig myConfig;

    @GetMapping("/myconfig")
    public MyConfig getMyConfig() {
        return myConfig;
    }
}

@RestController
public class ConfigController {

    @Autowired
    private Environment env;

    @GetMapping("/env")
    public String getEnv() {
        String port = env.getProperty("server.port");
        String name = env.getProperty("spring.application.name");
        return "Port: " + port + ", Name: " + name;
    }
}

/**
 * @SpringBootApplication
 * 组合注解,包含:
 * - @SpringBootConfiguration: 配置类
 * - @EnableAutoConfiguration: 自动配置
 * - @ComponentScan: 组件扫描
 */
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

/**
 * @RestController
 * = @Controller + @ResponseBody
 * 返回 JSON 数据
 */
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

/**
 * @Service
 * 标记业务逻辑层组件
 */
@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public User findById(Long id) {
        return userRepository.findById(id).orElse(null);
    }
}

/**
 * @Repository
 * 标记数据访问层组件
 */
@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByName(String name);
}

/**
 * @Component
 * 通用组件注解
 */
@Component
public class MyComponent {
    public void doSomething() {
        // 业务逻辑
    }
}

/**
 * @Configuration
 * 配置类注解
 */
@Configuration
public class MyConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

@RestController
@RequestMapping("/api")
public class WebAnnotationDemo {

    /**
     * @GetMapping - GET 请求
     */
    @GetMapping("/users")
    public List<User> getUsers() {
        return Arrays.asList(new User("张三"), new User("李四"));
    }

    /**
     * @PostMapping - POST 请求
     * @RequestBody - 接收 JSON 数据
     */
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        return user;
    }

    /**
     * @PutMapping - PUT 请求
     */
    @PutMapping("/users/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return user;
    }

    /**
     * @DeleteMapping - DELETE 请求
     */
    @DeleteMapping("/users/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 删除逻辑
    }

    /**
     * @PathVariable - 路径参数
     * @RequestParam - 查询参数
     * @RequestHeader - 请求头
     */
    @GetMapping("/search/{category}")
    public String search(
        @PathVariable String category,
        @RequestParam String keyword,
        @RequestParam(defaultValue = "1") int page,
        @RequestHeader("User-Agent") String userAgent
    ) {
        return "Category: " + category + ", Keyword: " + keyword +
               ", Page: " + page + ", User-Agent: " + userAgent;
    }
}

@Service
public class DependencyInjectionDemo {

    /**
     * @Autowired - 按类型自动注入(推荐)
     */
    @Autowired
    private UserRepository userRepository;

    /**
     * 构造器注入(推荐,final 保证不可变)
     */
    private final UserService userService;

    @Autowired
    public DependencyInjectionDemo(UserService userService) {
        this.userService = userService;
    }

    /**
     * @Resource - 按名称注入(JSR-250)
     */
    @Resource(name = "myBean")
    private MyBean myBean;

    /**
     * @Qualifier - 指定注入的 Bean
     */
    @Autowired
    @Qualifier("userServiceImpl")
    private UserService specificService;
}

/**
 * 自动配置类
 * @ConditionalOnClass: 当类路径存在指定类时生效
 * @ConditionalOnMissingBean: 当容器中没有指定 Bean 时生效
 * @EnableConfigurationProperties: 启用配置属性
 */
@Configuration
@ConditionalOnClass(MyService.class)
@EnableConfigurationProperties(MyProperties.class)
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService(MyProperties properties) {
        return new MyService(properties);
    }
}

/**
 * 配置属性类
 */
@ConfigurationProperties(prefix = "my.service")
public class MyProperties {
    private boolean enabled = true;
    private String name;

    // Getters and Setters
}

/**
 * META-INF/spring.factories
 */
// org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
// com.example.config.MyAutoConfiguration

/**
 * 用户管理 API
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 获取用户列表
     * GET /api/users?page=1&size=10&name=张三
     */
    @GetMapping
    public ResponseEntity<PageResult<User>> getUsers(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String name
    ) {
        PageResult<User> result = userService.getUsers(page, size, name);
        return ResponseEntity.ok(result);
    }

    /**
     * 获取单个用户
     * GET /api/users/1
     */
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            return ResponseEntity.notFound().build();
        }
        return ResponseEntity.ok(user);
    }

    /**
     * 创建用户
     * POST /api/users
     * Content-Type: application/json
     * Body: {"name": "张三", "age": 18, "email": "zhangsan@example.com"}
     */
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody @Valid User user) {
        User createdUser = userService.create(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(createdUser);
    }

    /**
     * 更新用户(完整更新)
     * PUT /api/users/1
     */
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(
        @PathVariable Long id,
        @RequestBody @Valid User user
    ) {
        user.setId(id);
        User updatedUser = userService.update(user);
        return ResponseEntity.ok(updatedUser);
    }

    /**
     * 部分更新用户
     * PATCH /api/users/1
     */
    @PatchMapping("/{id}")
    public ResponseEntity<User> patchUser(
        @PathVariable Long id,
        @RequestBody Map<String, Object> updates
    ) {
        User user = userService.partialUpdate(id, updates);
        return ResponseEntity.ok(user);
    }

    /**
     * 删除用户
     * DELETE /api/users/1
     */
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

/**
 * 统一响应实体
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ApiResponse<T> {
    private int code;           // 状态码
    private String message;     // 提示信息
    private T data;             // 数据
    private long timestamp;     // 时间戳

    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> ApiResponse<T> success(String message, T data) {
        return new ApiResponse<>(200, message, data, System.currentTimeMillis());
    }

    public static <T> ApiResponse<T> error(int code, String message) {
        return new ApiResponse<>(code, message, null, System.currentTimeMillis());
    }

    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>(500, message, null, System.currentTimeMillis());
    }
}

/**
 * 分页结果
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageResult<T> {
    private List<T> list;       // 数据列表
    private long total;         // 总记录数
    private int page;           // 当前页码
    private int size;           // 每页大小
    private int totalPages;     // 总页数

    public PageResult(List<T> list, long total, int page, int size) {
        this.list = list;
        this.total = total;
        this.page = page;
        this.size = size;
        this.totalPages = (int) Math.ceil((double) total / size);
    }
}

/**
 * 使用统一响应
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public ApiResponse<PageResult<User>> getUsers(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size
    ) {
        PageResult<User> result = userService.getUsers(page, size);
        return ApiResponse.success(result);
    }

    @PostMapping
    public ApiResponse<User> createUser(@RequestBody @Valid User user) {
        User createdUser = userService.create(user);
        return ApiResponse.success("用户创建成功", createdUser);
    }
}

/**
 * 用户实体(包含校验注解)
 */
@Data
public class User {

    private Long id;

    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度必须在2-20之间")
    private String name;

    @NotNull(message = "年龄不能为空")
    @Min(value = 1, message = "年龄最小为1岁")
    @Max(value = 150, message = "年龄最大为150岁")
    private Integer age;

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;

    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
}

/**
 * Controller 中使用 @Valid
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ApiResponse<User> createUser(@RequestBody @Valid User user) {
        User createdUser = userService.create(user);
        return ApiResponse.success(createdUser);
    }
}

/**
 * 自定义校验注解
 */
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = IdCardValidator.class)
public @interface IdCard {
    String message() default "身份证号格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

/**
 * 自定义校验器
 */
public class IdCardValidator implements ConstraintValidator<IdCard, String> {

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null || value.isEmpty()) {
            return true;
        }
        // 身份证号校验逻辑
        return value.matches("^\\d{15}|\\d{18}$");
    }
}

/**
 * 全局异常处理器
 * @ControllerAdvice: 全局 Controller 增强
 * @RestControllerAdvice = @ControllerAdvice + @ResponseBody
 */
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    /**
     * 处理参数校验异常
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<Void> handleValidationException(MethodArgumentNotValidException e) {
        BindingResult bindingResult = e.getBindingResult();
        StringBuilder sb = new StringBuilder();

        for (FieldError fieldError : bindingResult.getFieldErrors()) {
            sb.append(fieldError.getField())
              .append(": ")
              .append(fieldError.getDefaultMessage())
              .append("; ");
        }

        String message = sb.toString();
        log.error("参数校验失败: {}", message);
        return ApiResponse.error(400, message);
    }

    /**
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public ApiResponse<Void> handleBusinessException(BusinessException e) {
        log.error("业务异常: {}", e.getMessage());
        return ApiResponse.error(e.getCode(), e.getMessage());
    }

    /**
     * 处理资源未找到异常
     */
    @ExceptionHandler(ResourceNotFoundException.class)
    public ApiResponse<Void> handleNotFoundException(ResourceNotFoundException e) {
        log.error("资源未找到: {}", e.getMessage());
        return ApiResponse.error(404, e.getMessage());
    }

    /**
     * 处理其他异常
     */
    @ExceptionHandler(Exception.class)
    public ApiResponse<Void> handleException(Exception e) {
        log.error("系统异常: ", e);
        return ApiResponse.error("系统异常,请联系管理员");
    }
}

/**
 * 自定义业务异常
 */
@Data
@EqualsAndHashCode(callSuper = true)
public class BusinessException extends RuntimeException {
    private int code;

    public BusinessException(String message) {
        super(message);
        this.code = 500;
    }

    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }
}

/**
 * 资源未找到异常
 */
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

/**
 * 文件上传下载 Controller
 */
@RestController
@RequestMapping("/api/files")
@Slf4j
public class FileController {

    @Value("${file.upload.path:./uploads}")
    private String uploadPath;

    /**
     * 单文件上传
     * POST /api/files/upload
     */
    @PostMapping("/upload")
    public ApiResponse<String> uploadFile(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return ApiResponse.error("文件不能为空");
        }

        try {
            // 获取原始文件名
            String originalFilename = file.getOriginalFilename();
            // 生成新文件名(UUID + 扩展名)
            String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
            String newFilename = UUID.randomUUID().toString() + extension;

            // 创建上传目录
            File uploadDir = new File(uploadPath);
            if (!uploadDir.exists()) {
                uploadDir.mkdirs();
            }

            // 保存文件
            File dest = new File(uploadDir, newFilename);
            file.transferTo(dest);

            log.info("文件上传成功: {}", newFilename);
            return ApiResponse.success("文件上传成功", newFilename);

        } catch (IOException e) {
            log.error("文件上传失败", e);
            return ApiResponse.error("文件上传失败");
        }
    }

    /**
     * 多文件上传
     */
    @PostMapping("/batch-upload")
    public ApiResponse<List<String>> uploadFiles(@RequestParam("files") MultipartFile[] files) {
        List<String> filenames = new ArrayList<>();

        for (MultipartFile file : files) {
            if (!file.isEmpty()) {
                try {
                    String originalFilename = file.getOriginalFilename();
                    String extension = originalFilename.substring(originalFilename.lastIndexOf("."));
                    String newFilename = UUID.randomUUID().toString() + extension;

                    File dest = new File(uploadPath, newFilename);
                    file.transferTo(dest);

                    filenames.add(newFilename);
                } catch (IOException e) {
                    log.error("文件上传失败: {}", file.getOriginalFilename(), e);
                }
            }
        }

        return ApiResponse.success("上传成功", filenames);
    }

    /**
     * 文件下载
     * GET /api/files/download/xxx.jpg
     */
    @GetMapping("/download/{filename}")
    public ResponseEntity<Resource> downloadFile(@PathVariable String filename) {
        try {
            File file = new File(uploadPath, filename);
            if (!file.exists()) {
                return ResponseEntity.notFound().build();
            }

            Resource resource = new FileSystemResource(file);

            return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION,
                       "attachment; filename=\"" + filename + "\"")
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .body(resource);

        } catch (Exception e) {
            log.error("文件下载失败", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }
}

/**
 * 用户实体
 * @Entity: 标记为 JPA 实体
 * @Table: 指定表名
 */
@Entity
@Table(name = "tb_user")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {

    /**
     * @Id: 主键
     * @GeneratedValue: 主键生成策略
     * - AUTO: 自动选择
     * - IDENTITY: 自增(MySQL)
     * - SEQUENCE: 序列(Oracle)
     * - TABLE: 表生成器
     */
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    /**
     * @Column: 字段映射
     * - name: 字段名
     * - length: 长度
     * - nullable: 是否可空
     * - unique: 是否唯一
     */
    @Column(name = "username", length = 50, nullable = false, unique = true)
    private String name;

    @Column(name = "age")
    private Integer age;

    @Column(name = "email", length = 100)
    private String email;

    /**
     * @CreatedDate: 创建时间
     * @LastModifiedDate: 更新时间
     * 需要在启动类添加 @EnableJpaAuditing
     */
    @CreatedDate
    @Column(name = "create_time", updatable = false)
    private LocalDateTime createTime;

    @LastModifiedDate
    @Column(name = "update_time")
    private LocalDateTime updateTime;
}

/**
 * 启动类开启 JPA 审计
 */
@SpringBootApplication
@EnableJpaAuditing
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

/**
 * UserRepository
 * 继承 JpaRepository<实体类, 主键类型>
 * 自动拥有 CRUD 方法
 */
@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    /**
     * 方法名查询
     * 命名规则: findBy + 属性名 + 关键字
     *
     * 关键字:
     * - And: 与
     * - Or: 或
     * - Between: 范围
     * - LessThan: 小于
     * - GreaterThan: 大于
     * - Like: 模糊查询
     * - OrderBy: 排序
     */

    // 根据名称查询
    List<User> findByName(String name);

    // 根据名称和年龄查询
    List<User> findByNameAndAge(String name, Integer age);

    // 根据名称模糊查询
    List<User> findByNameLike(String name);

    // 根据年龄范围查询
    List<User> findByAgeBetween(Integer minAge, Integer maxAge);

    // 根据年龄排序
    List<User> findByOrderByAgeDesc();

    /**
     * @Query 注解查询
     * JPQL: Java Persistence Query Language
     */
    @Query("SELECT u FROM User u WHERE u.name = ?1")
    User findByNameJPQL(String name);

    @Query("SELECT u FROM User u WHERE u.name = :name AND u.age = :age")
    User findByNameAndAgeJPQL(@Param("name") String name, @Param("age") Integer age);

    /**
     * 原生 SQL 查询
     */
    @Query(value = "SELECT * FROM tb_user WHERE username = ?1", nativeQuery = true)
    User findByNameNative(String name);

    /**
     * 更新操作
     * @Modifying: 标记为修改操作
     * @Transactional: 事务
     */
    @Modifying
    @Transactional
    @Query("UPDATE User u SET u.age = :age WHERE u.id = :id")
    int updateAgeById(@Param("id") Long id, @Param("age") Integer age);

    /**
     * 删除操作
     */
    @Modifying
    @Transactional
    @Query("DELETE FROM User u WHERE u.name = :name")
    int deleteByName(@Param("name") String name);
}

@Service
@Slf4j
public class UserService {

    @Autowired
    private UserRepository userRepository;

    /**
     * 查询所有用户
     */
    public List<User> findAll() {
        return userRepository.findAll();
    }

    /**
     * 根据 ID 查询
     */
    public User findById(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("用户不存在: " + id));
    }

    /**
     * 创建用户
     */
    @Transactional
    public User create(User user) {
        return userRepository.save(user);
    }

    /**
     * 更新用户
     */
    @Transactional
    public User update(User user) {
        // 检查用户是否存在
        User existingUser = findById(user.getId());

        // 更新字段
        existingUser.setName(user.getName());
        existingUser.setAge(user.getAge());
        existingUser.setEmail(user.getEmail());

        return userRepository.save(existingUser);
    }

    /**
     * 删除用户
     */
    @Transactional
    public void delete(Long id) {
        userRepository.deleteById(id);
    }

    /**
     * 分页查询
     */
    public PageResult<User> getUsers(int page, int size, String name) {
        // 创建分页对象(page 从 0 开始)
        Pageable pageable = PageRequest.of(page - 1, size, Sort.by("id").descending());

        // 分页查询
        Page<User> pageResult;
        if (name != null && !name.isEmpty()) {
            pageResult = userRepository.findAll(
                (root, query, cb) -> cb.like(root.get("name"), "%" + name + "%"),
                pageable
            );
        } else {
            pageResult = userRepository.findAll(pageable);
        }

        return new PageResult<>(
            pageResult.getContent(),
            pageResult.getTotalElements(),
            page,
            size
        );
    }
}

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    private Long id;
    private String name;
    private Integer age;
    private String email;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
}

/**
 * UserMapper
 * @Mapper: 标记为 MyBatis Mapper
 */
@Mapper
public interface UserMapper {

    /**
     * 查询所有用户
     */
    List<User> findAll();

    /**
     * 根据 ID 查询
     */
    User findById(@Param("id") Long id);

    /**
     * 插入用户
     */
    int insert(User user);

    /**
     * 更新用户
     */
    int update(User user);

    /**
     * 删除用户
     */
    int deleteById(@Param("id") Long id);

    /**
     * 根据名称查询
     */
    List<User> findByName(@Param("name") String name);

    /**
     * 分页查询
     */
    List<User> findByPage(@Param("offset") int offset, @Param("limit") int limit);

    /**
     * 统计总数
     */
    long count();
}